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Introduction 


This road mep was designed to help you to find your way around the various 
documents describing prograrn development for the Lisa It will help you decide 
which software you need to learn more about, which softwere you can ignore for the 
moment, and how you should proceed in studying the rest of the technical 


documenta atior:. 


General Overview of the Environment: Available 


There ere at many ways of writing progrems as there are creative programmers. 
However, Apple supports only three general styles of programs that you car write for 
the Lixa: those written for 1) the Workshop environment, 2) the QuickPort 
emvironment, and 3) the ToolKit ervironment. Programs written for any of these 
environments can use most of the same units and libraries, but there are some 
important differences of which you should be awere. 


The Workshop (Figure 1) provides @ simple non-window, character and grephic 
environment within which a program mey run. Prograrns written to run in this 
environment may use Pascal's built-in 1/0 for both files and textual display to the 
console’s termina) ermuletar, ar they may directly utilize the Lisa OS's file system 
primitives. They may also use the QuickDraw unit for drawing bitmap graphics ard 
displaying text in a variety of fonts with verious attributes, and may utilize a variety 
of other useful library routines. These programs are not able to use the Lisa Desktog: 
libraries dealing with windows, menus, and dialog boxes, nor do they have easy acces: 
to Lisa Office System documents. 


In addition to providing these run-time facilities, the Workshop also includes 4 
Command shell which makes available to users an extensive set of facilities for: 1) 
Interactive program development in Pascal, Assembly, BASIC, and COBOL; 2) File an: 
device manipulation; and 3) Interactive and batch program execution and control. 


@uickFort (Figure 2) provides the simplest Desktop erwironmert, at least from the 
programmer's viewpoint. In most respects, writing a program for the QuickPort 
environment i: identical to writing one for the Workshop environment. Using Pascal’: 
bufllt-in 1/0 facilities, programs written for QuickPart may do textual display to a 
variety of window-based terminal emulators, and may also display graphics using 
QuickDraw. These programs do not directly use the Lisa Desktop Ibreries, and ere : 
fact, unaware of such things as the window environment, the mouse, and menus. The 
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may, however, exchange information witn Lisa Office System documents via the 
Cut/Paste mechanism. . 


The ToolKit (Figure 3) provides the most complete access to the Desktop facilities. 
From the programmer's viewpoint, it also requires the most knowledge of these 
facilities. Programs written using the ToolKit use the Generic Application and may 
use any of the ToolKit building blocks, which provide easy, controlled access to the 
Lisa Desktop libraries, the mouse, and menus. They may also exchange information 
with Lisa Office System documents vie the Cut/Paste mechanism. 


Overview of the Pieces 


is a set of units thet are USEd and linked with a program which is to be 
run in the Desktop environment. QuickPort then provides the program with a 
“terminal window", to which the program's console 1/0 mey be directed through the 
use of Pascal's built-in Text 1/0 facilities. The program simply makes ReadLn and 
WriteLn calls to display text or receive keyboard input. QuickPort code hides from 
the program such issues as cutting and pasting information from other Desktop 
applications, communicating with the Desktop shell, growing and shrinking the window, 
covering and uncovering the window, and activating or deactivating the program. Fer 
@ program using QuickPort, such issue: are of mo concern. 


The YoolK# i: a set of libraries that provides standard Lisa application behevior, 
including windows that can be moved, resized, and scrolled, pull-down menus with 
standard functions such as saving and printing, and the Cut/Paste mechanism. The 
Toolkit: defines the parts of an--application common to.all Lita applications. The 
object-orierted structure of the ToolKit allows you to implement your application as 
extensions to the "Generic Application”. 


The Lisa Qperating System provides the program with an environment in which 
multiple processes can coexist, with the ability to cormmunicete and there deta It 
provides a device-independent file systern for 1/0 and inforrnation storage, and hendles 
exceptions (software interrupts} and mermmcry management for both code and deta 
segments. 


PASLIB is the Pascal run-time support library. Most of the routines in PASLIS 
support the Pascal built-in facilities, including routines for initialization, integer 
arithmetic, data and string manipulation, sets, range checking, the heap, and 1/0. 


Floating Poirk Libraries provide numeric routines which implement the proposed IEEE 
Floeting Point Standerd (Standard 754 for Binary Floating-Point Arithmetic), and 
higher-level mathematical algorithms. FPLib provides Single (32-bit), Double (64-bit), 
and Extended (80-bit) floating-point data types, a 64-bit Integer data type, conversion 
from one arithmetic type to another (or to ASCII), arithmetic operations, 
transcendental functions, end tools for handling exceptions. MathLib provides, amorig 
others, algorithms such as extra elementary functions, sorting, extended conversion 
routines, financial analysis, zeros of functions, end linear algebra 


QuickDraw 1s a unit for doing bit-mepped graphics. It consists of procedures, 
functions, and data type: you need to perform highly complex graphic operetion: ver; 
eatily and very quickly. You can draw text characters: in a number of fonts, with 
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variations that include boldface, italic, underlined, and outlined; you can draw 
erbitrary or predefined shapes, either hollow or filled, you can draw straight lines of 
any length and width; or you can draw any combination of these items, with a single 
procedure call. 


The Qesktop Libraries provide window, graphics, mouse, and menu routines used by 
all Office Systerm applications. They are not directly called by any programs written 
for the three run-time environments discussed here, but provide the hidden foundation 
for both the QuickPort and the ToolKit environments. 


The Hearoware Interface unit lets you access Lisa hardware elements such as the 
mouse, the cursor, the display, the contrast control, the speaker, the keyboard, the 
micro- and millisecond timers, and the hardware clock/calendar. 


The Stancard Unt lets you do string, character, and file-name meripulation, 
promoting, retrieval of messages from disk files, abort exec file processing, and 
conversions between numbers and strings. 


The D¥rimitives unit provides you with fast, efficient text-file input and output. 


The Program Communication unit allows programs to communicate with each other 
and with the Workshop shell. 


Lisafug allows you to examine and modify memory, set breakpoints, assemcie and 
disassemble instructions, and perform other functions for run-time detugging. 


More Detatl 


QuickPort: A program which is to make full use of the capabilities of the Lisa Office 
System will be structured as an endless loop, within which the program continually 
polls the Window Manager for any events it should respond to. We will refer to such 
@ program as an /ntegrated Frogram An integrated program must handle sucn 
asynchronous events as the program’: window being activated or deactivated, the 
window being opened, closed, moved, resized, or. needing update, the mouse button 
going down or up, and a key going down or up. The program must also be a good 
citizen in Lisa’: multi-tasking but non-preemptive scheduling ervironment by 
volunteering periodically to yield the CPU to ery other process needing service. 
These are just a few of the important characteristics of an integrated program. The 
result of @ program following these and other guidelines will be that it exnibits the 
same consistent, responsive behavior as other Apple-written programs like LiseOraw. 


@uickFort is a collection of pleces which make writing programs for the Office 
System's window environment es easy 83s writing them for the Warkshop's non- window 
environment. NOTE: In order to differentiate the QuickPort modules from the 
program which uses them, we will refer to the program itself as a WMani/la Frogram 
QuickPort allows the vanilla program to be more traditionally structured, as if its use: 
interfacing were being done through a smart text/graphics terminal; the vanilla 
program presents {its display to the usez by @ combination of text 1/0 calls (e.g., 
WriteLn/ReadLn) and QuickDraw calls (e.g., OrawString/PaimRect). The QuickPort 
modules handle all events from the Window Manager, provide for yielding the CPU! tc 
competing procetses at specific points, and in general shelter the program from the 
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sometimes tricky requiremerts of writing an integrated program for the Lisa Office 
Systern. 


QuickPort provides the vanilla progrem with a window, which mey be divided into a 
Tert Pare! earnda QuickCraw Fanel for displaying both textual and graphic 
informetion. Each of these optional panels is corfigurable in size and locetion, anc 
mey be independently scrotled horizontally or vertically. Text and Graphics windows 
may be overlaid, so the resulting window presents a composite of both types of 
output. The window may be resized, moved, covered, or uncovered without the ; 
vanilla program even being awere of such events. Textual end graphic information 
may be exchanged between a vanilla program's documert and other documents, 
whether vanilla or integrated, by using the familiar Cut/Paste mechanism. Without 
any effort on the part of the vanilla program, the end user is given a large measure 
of control aver the window's configuration end behavior, using mouse and menu 
actions supported by QuickPort. 

The user may request printing of either the text panei or the graphics panel. In 
addition, venilla programs may produce printed output under program control by 
writing to the -PRINTER Jogicel device. Whereas, in the Workshop environment, 
printing is immediate (each line priming es soon as the program “writes” it), in the 
QuickPort/Desktop environment printing is al] spooled. This mesns that the printed 
output of a vanilla program will be submitted to the Office system's PrintShop, which 
determines from the print queve when the docurnent will be printed. 


The Fert Panel emulates a terminal display which corresponds to the Pascal built-in 
OUTPUT file, the built-in INPUT file, and the -CONSOLE and -KEYBCARD logical 
devices. Apple provides emulators for the WTI and SADC terminals, end makes 
it possible for you to either custormze them or create entirely new termirial 
emuletort. These terminal emulators sre actually stiters which pre-process the 
character output stream destined for the Standard Terminal Lint. which provides the 
Text Panel display. Each emulator’s job is to recognize the terminal-specific 
character sequences imbedded in the output stream which ere commands to the 
terminal, and to call upon the Standard Terminel Unit to take the appropriate actions. 
A program’ may eliminate the filtering step, if desired, by calling directly upon the 
Standard Terminal Unit for displey actions. 


The Graphics Fane! allows your program to display graphics on a bitmap which Is a 
maximum of 720 pixels wide by 364 pixels high--the same size as Lisa's physical 
screen bitmap. Thi: panel can be resized by the user or under program control, ard 
can be scrolled horizontally and vertically to display different parts of the entire 
bitmep. The Graphics Panel supports every QuickDraw call, including those related to 
setting foreground and beckground colors for printed output. An epplicetion mey 
write anywhere in the coordinate plane of its graphics panel (‘grafPort', to use 
QuickDraw's terminology), without having to worry sbout where its window ist placed 
on the screen or what other windows are in from of it. QuickDraw, with a little help 
from the Window Manager, keeps the application's output from getting out of the 
gaphics panel or from clobbering other windows. 
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The ToolKit: The ToolKit is a set of libraries that provides standard beteavior that 
follows the design principles characterizing Lisa applications: 


« Extensive use of graphics, including windows and the mouse pointer. 
® Use of pull-down menus for commands. 

« Few or no operating modes. 

e Date transfer between documents by simple cut and paste operations. 


For example, al] Lisa applications have windows that can be moved eround the screen, 
and that can usually be resized and scrolled. The ToolKit takes care of all these 
functions. The ToolKit also displays @ menu ber for the active application, and 
provides a number of standard menu functions, such as saving, printing, and settinc 
aside. 


However, the ToolKit is more than 9 set of libraries. Because the ToolKit is writte”. 
using Clascal, the ToolKit is almost s complete program by itself. You can, in fact, 
write a five-line main program, compile it, link it with the ToolKit, and run it. Wet 
results is the Generic Application. 


The Generic Application has many of the standard Lisa application cheracteristics. & 
piece of Generic Application stationary can be torn off, and, when the new documert 
is opened, it presents the user with a window with scroll bars, split controls, size 
control, and a title bar. The mouse pointer is handled correctly when it Is over the 
window. The window can be moved resized, and split into multiple panes. There 13 4 
menu bar with a few standard functions, so that the generic document can be saved, 
Printed, and set aside: The tingle Generic Application.process can mansoe any 
number of documents. You cannot, however, do anything within the window, aside 
from creating panes. The space within the window, along with the additional menu 
fuctioris, is the responsibility of the real application. 


Therefore, when you write a Lisa application using the ToolKit, you essentially write 
extensions to the Generic Application. It is very easy to write extennors to any 
Clascal prograrn. To insert your application's functions, you create a set of 
subclasses, including methods to perform the work of you application, and then you 
write a simple main program, and compile and link it with the ToolKit. 


Whenever necessary, the ToolKit calls your application's routines. For example, if the 
user scrolls the document, the ToolKit tells your program to redrew the changed 
portions of the window. Your program does not need to be concerned with when 
redrawing is required. 


One effect of Clascal is thet you can write application: in steps. You can begin by, 
doing the least amourd possible, and get an application that does very little, but wil! 
run. You can then extend your application bit by bit, checking as you go. Thit 
Cheracterjstic of Clascal makes it easy to extend the capabilities of ToolKit progrems, 
even years after the original program. 


The ToolKit's debugger, KitBug provides run-time debugging of ToolKit Cle:cal 
programs. It allows you to do performance measurements, set breakpoints and traces, 
single-step through your program one stelement et a time, and do high-level 
examination: of data objects 
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ovides a file systern for 1/0 and information storage, and handles exceptions 
software Interrupts) and memory management. 


The Filé Sistem provides input and output. I accesses devices, volumes, and files. 
Each object, whelner a printer, disk file, or any other type of object, is referenced by 
@ pathname. Every 1/0 operation {is performed as an uninterpreted byte stream. Using 
the File System, all 1/0 it device-independent. The File System alto provides device- 
specific control operations. 


A process consists of an executing program and the data associated with it. Several 
processes can exist et once, and will appear to run simultaneously beceuse the 
processor it multiplexed emong ther. These processes can be broken into multiple 
segments which ere autometicaliy swapped ims memory s: needed. Communication 
between processes is accomplished through events and exceptions. An event is a 
message sent from one process to another, or from a process to itself, that is 
delivered to the receiving process only when the process asks for it. An erception is 
a special type of event that forces itself on the receiving proces1:. In addition to a 
set of system-defined exceptions (errors), such as division by zero, you can use the 
system calls provided to define any other exceptions you went. 


Memory management routines handle data segmerts and code segments. A cata 
segment is a file that can be placed in memory and accessed directly. A code 
segment it a swapping unit that you can define. If a process uses more memory 
than the available RAM, the OS will swap code segments in and out of memary as 
they are needed. 


PASLIB. PASLIB is the Pascal run-time support library. It provides the procedure: 
end functions thet ere bullt Into the Pascal language, acts as the run-time interface 
to the Gperating System, and “completes" the 68000 instruction ret by oroviding 
routines for the compiler-generated code to call upon in lieu of actuel hardware 
instructions. 


PASLIB routines are called with all parameters passed on the stack. There is an 
initialization routine to initialize necessary variables, libraries, and exception-hendlers 
end set up global file buffer addresses, and a termination routine to kill proceszes. 
You can do four-byte integer arithmetic. Oata can be moved, or scanned for a 
perticuler cheracter. String manipulation routines include concetenating, copying, 
inserting or deleting a substring, determining the position of a substring, and 
comparing strings for equelity. Set manipulation routines let you find set 
intersections or differences; adjust _the-size-of—a-set,-end_compare_set: for. equality. 
There ere range-checking end string renge-checking routines. Heap routines let you 
allocate memory in the heap, merk of release the heap, check available memory in 
the heap, and check the heep result. 1/0 routines let you read and write lines, 
cheracters, strings, packed arrays of characters, boaleans, and integers, as well at 
check for e keypress or an end-of-line, and send page marks. File 1/0 routines 
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Floeting-Poirnt Libraries: The Lisa provides arithmetic, elementary functions, and ” 
higher level mathematical algorithms in its intrinsic units FPLib and MathLib, which 
ere contained in the file IOSFPLIB. 


FPLib provides the same functionality as the SANE and Elems units on the Apple ) | 
and ///, including: 


° Arithmetic for all floating-point and Comp types. 

® Conversions betweer: numerical types. 

e Corversions between numerical types, ASCII strings, and intermediate forms. 
e Contro] of rounding modes and numerical exception handling. 

e Comirnon elementary functions. 


MathLib provides the extra procedure: available only on the Lisa: 


e Extra environments procedures. 

e Extra elementary functions. 

e Miscellaneout utility procedures. 

* Sorting. 

e Free-format conversion to ASCIL. 

© Correctly rounded corversion between binary and decimal. 
» Finencial analysis. 

e Zeros of functions. 

e Linear algebra 


QuickDraw. Virtually ell of Lisa's graphics are performed by the QuickDraw unit. 
You can draw text, lines, and shapes, and you can draw pictures combining these 
elements. Orswing can he done to many distinct “ports” on the screen, each of which 
it a complete drawing environment. You can "clip" drawing to arbitrary eveas, to 
thet you only draw where you want. You can draw to an off-screen buffer without 
disturbing the screen, then quickly move your drawing to the screen. 


Text characters are avilable in a number of proportionally-spaced fonts. Any font 
can be crawn in any sizeé--if a font isn't available in a perticular size, QuickOraw 
will scale it to the specified size. You can draw characters in any combinetion of 
boldface, italic, underlined, outlined, or shadowed styles. Text can be condensed or 
extended, and it can be justified (aligned with both a left and a right margin). 


. Straight toes can be drawn in eny length and width, and can be solld- colored (black, 


white, or thedes of gray) or patterned. 


Shapes defined by QuickDraw are rectangles, rectangles with rounded corners, full 
circles or ovals, wedge-shaped sections of circles or ovals, and polygons. In addition, 
you can describe any erbitrery shape you want. All shapes can be crawn either 
hollow (just an outline, which has all the wicth and pattern cheracteristics of other 
lines) or solid (filled in with a color or pattern thet you define). 
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QuickDraw lets you combine any of these elements into a picture, which can then be 
drawn--to any scale--with a single procedure call. 


Three-dimensional graphics capabilities are also available, in a unit called Graf30, 
which is layered on top of the QuickOraw routines. Gref3D lets you draw three- 
dimensional objects in true perspective, using real veriables and world coordinates. 


The Hardware Interface. The Hardwere Interface unit lets you access Lisa hardware 
elements such as the mouse, the cursor, the display, the speeker, the keyboard, and 
the timers and clocks. 


Adouse routines determine the location of the mouse, tet the frequency with which 
software knowledge of the mouse location is updated, change the relationship between 
phytical mouse movement and the movemert of the curtor on the tcreen, and keep 
track of now far the mouse nas moved since Goat time. 

Cursor routines let you define different cursors, track mouse movements, and displey 
@ busy cursor when an operation takes a long time. 


Screen-control routines can set the size of the screen, and set contrast and 
automatic fading levels. 


Speaker routines allow you to find out and set the speaker volume, and create 
sounds. 


Routines ere provided to handle the different se,dcarcs available for the Lisa, as 
well ar the mouse button and-plug, the-diskette buttons and insertion switches, and 
the power switch. You can find out which keyboard is attached, and tet the systern 
to belleve that a different physical keyboard {is connected. You can check to see 
what keys (including the mouse button) are currently being held down, look at or 
return the events in the keyboard queue, and read and set the repeat rates for 
repeatable keys. 


Date and time routines let you access the microsecond and millisecond timers and 
check or set the date and time. 


The Standard Unit: The Standard Unit (StdUnit) is an intrinsic unit providing a 
number of standard, generally-useful furictions. The functions are divided into areas 
of functionality: character and string manipulation, file name manipulation, prompting, 
retrieval of error messages frorn disk files, Workshop support, and conversions. 


The unit provides types for standard strings and for sets of characters, definitions for 
@ number of standard characters (such as <CR) and <BS>), and procedures for case 
conversion on characters and strings, trimming blanks, and appending strings ard 
characters. 


File narne manipulation functions let you determine if a pathname is a volume or 
device mame only, add file name extensions (such as ".TEXT"), split a pathname into 
its three basic components (the device or volume, the file name, and the extension) 
put the components back together into a file name, and modify a file neme given 
optional defaults for missing volume, file, or extension components. 
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Prompting procedures let you get characters, strings, file names, integers, yes or no 
responses, end so forth from the corsole, providing for default values where 
appropriate. 


Special Workshop functions let you stop the execution of an EXEC file in progress, 
find out the name of the boot and current process volumes, and open system files, 
looking et the prefix, boot, and current process volume: when trying to access a file. 


Conversion routines Jet you convert between INTEGERS (or LONGINTs) and strings. 


The DPrimitives Unit: The lOPrimitives unit provides you with fast, efficient 

text-file input and output routines with the functionality of the Pascal 1/0 routines. 
It includes routines for reading characters or lines, and for writing characters, Hines 
strings, and integers, plus the low-level routines on which the others are based. 


The Program Communications Unit: The Program Communications unit (Frog? omm) 
Provides ttree mechanisms for communication between one program and another cr 
between 6 program and the shell. The first two involve strings sent from oe progam 
to the shell; one tells the shell which program to run next, the other 1s @ ‘Yeturn 
string” thet can be read by the exec file processor to tell an exec file, for example 
whether the program completed successfully. The third mechanism involves reading. 
from and writing to a 1K byte communications buffer, globa! to the Workshop. Using 
the unit, a program can invoke another program and provide its input trwough the 
buffer, without user intervention. 


LisaBug LisaBug provides commands for displaying and setting memory locations and 
Tegisters, for assernbling and disassembling instructions, for setting breakpoints and 
traces to trace program execution, for manipulating the memory management 
hardware, and for measuring execution times using timing functions. Utility 
commends are also available to clear the screen, print either the main screen or the 
LisaBug screen, change between decimal! and hexadecimal, change the setting of the 
NMI key, and display the values of symbols. 
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Where to Go from Here 


The Lisa development software is not fully docurnented yet. The following is a list of 


# Confidential 


what is available, some of it only irternelly, as of this publication. Note that the 
spring-release menuals will be organized differently from the current versions, and 
will incorporate much of the information that is now in the internals documentation 


or in teparete documents. 


Pascal Reference Manual for the Lisa 
includes: QuickOraw 
Hardware Interface 
Floeting-Point Library 


Operating Svstern Reference Manual for the Lisa 
torkshop Ulser’s Guide for the Lisa 


Lisa Development $)-stem Internals Doturnent ation 
includes: Pascal Run-Time Library 
Standerd Unit 
LisaBug 
Floating-Point Libraries 


QuickFort Aplications User Guide* 
QuickFort Frogramvmner’s Guide® 

An Introduction to Clascal 

Clascal Sel-Stuas: 

ToolKit Reference Manual 

ToolKit Training Segments 


Aemerics Manual: A Guide to Using the Apple “i Pascal SANE and Elems Units 


FPLib provides the sarne functionality as these units. 
Mathl io Guide® 


*These manuals currently in rough draft form. 
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Floating-Poirt Libraries 
JEEE Numerics, Math Algorithms 


Mouse, Keyboard, Clocks, Speaker 


Sanderd Unit 
Strings, Prompts, Error Msgs, misc 


10 Primitives 


Fast Text File 1/0 


Program Communication 
Inter-program and Shell Cormmunicstion 


Run-Time Library 


1/70, Heap, Strings, Math 


_ Lisa Operating System 


Memory Mgmt, File System, Process Mgmt 


Figure 1 
The Workshop Run-Time Environment 


KEY to Figures 1, 2, & 3 


Ck kre Fy. ———E——_—ES 


Description of what It does indicates opticess units tar may de used 
OO 


> 


Roan Afan- 


PTITTITTITIST TTT TTT Tey | a ee RRUGHR EL EE EERE R SRS ER ELE 
4 KIT PROGRAM ll udddo 
( PESTS TSTESTES TESST S SCPE PE Rear eDMPORT TITET TIPS TIT Ter Tee sire 


Floating-Poirt Libraries 


IEEE Numerics, Math Algorithms 


Herdwere Interface 
Clocks, Speaker 


Standard Unit 
Strings, Prompts, Error Msgs, misc 


Patcal Run-Time Library 
1/0, Heap, Strings, Math 
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Floating-Poirt Libraries 
JEEE Nurmeric:, Math Algorithms 


Herdwere Interface 
Clocks, Speaker 


Patcal Run-Time Library 


1/0, Heap, Strings, Math 
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Generic Application, Bldg Blocks 


Window Mgr, Storage Mgr Font Mgr, Print Mgr” 


oalkKit 


Virtual-Terminal Window 
(| Generic Application, Bldg Blocks 


Desktop Libraries 
Window Mgr, Storage Mgr, Font Mgr, Print Mor 


Bit-Map Graphics. 


Lisa Operating System 
Memory Mgmt, File System, Process Mgmt 


Bit-Map Grephics 


Lita Operating Syrtem 
Memory Mgmt, File Systern, Process Mgmt 


Figure 3 
The ToolKit Run-Time Environment 


Figure 2 
The QuickPart Run-Time Environment Read Arap- 1? 
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